home
***
CD-ROM
|
disk
|
FTP
|
other
***
search
/
Aminet 5
/
Aminet 5 - March 1995.iso
/
Aminet
/
dev
/
gui
/
BGUI11B.lha
/
docs
/
listviewclass.doc
< prev
next >
Wrap
Text File
|
1994-12-06
|
30KB
|
760 lines
$RCSfile: listviewclass.doc,v $
Description: Listviewclass documentation.
Copyright: (C) Copyright 1994 Jaba Development.
(C) Copyright 1994 Jan van den Baard.
All Rights Reserved.
$Author: jaba $
$Revision: 1.8 $
$Date: 1994/11/15 14:26:26 $
------------------------------------------------------------------------------
TABLE OF CONTENTS
listviewclass/--background--
listviewclass/Methods
listviewclass/Attributes
listviewclass/--background-- listviewclass/--background--
NAME
Class: listviewclass
Superclass: baseclass
Include File: <libraries/bgui.h>
FUNCTION
To provide a gadget simular to the gadtools.library it's listview
kind. The lisview class does how ever have extended functionality
like hooks for entry creation, entry comparrison, entry and title
rendering. Also a multi-selection mode is available. Opposed to the
gadtools version this class does not require the usage of list and
nodes. All kind of data can be added to the listview as entries
providing that you supply hook routines to handle this data.
Objects from this class send out the following attribute pairs in
their notification events:
GA_ID - Gadget object ID.
LISTV_Entry - Pointer to the selected entry.
LISTV_EntryNumber - Logical number of the selected entry.
listviewclass/Methods listviewclass/Methods
NOTE
Most of the methods described below can also contain a pointer to a
GadgetInfo structure. This pointer does not have to be valid. All
actions will be done only if you want to let the action also be shown
visually you need to pass a valid pointer to a GadgetInfo structure.
NEW METHODS
LVM_ADDENTRIES -- This method can be used to add more than one entry
after the listview object has been created. It uses the
following custom message structure:
struct lvmAddEntries {
ULONG MethodID; /* LVM_ADDENTRIES */
struct GadgetInfo *lvmaGInfo; /* See note above. */
APTR *lvma_Entries;
ULONG lvma_How;
};
lvma_Entries -- This must point to a NULL-terminated array of
pointers to the entries to add.
lvma_How -- Here you can select where the entries are added.
The following positions are possible:
LVAP_HEAD -- The entries are added at the top of the
list.
LVAP_TAIL -- The entries are added at the bottom of
the list.
LVAP_SORTED -- The entries are added sorted according
to the sorting method active. In the
attributes section of this documentation you
can find more about the sorting possibilities.
This method returns TRUE uppon succes and FALSE if one or more
of the entries failed to be added.
LVM_ADDSINGLE -- This method can be used to add a single entry to the
listview object after it has been created. It uses the
following custom message structure:
struct lvmAddSingle {
ULONG MethodID; /* LVM_ADDSINGLE */
struct GadgetInfo *lvma_GInfo; /* See note above. */
APTR lvma_Entry;
ULONG lvma_How;
ULONG lvma_Flags;
};
lvma_Entry -- This must point to the entry which needs to be
added to the listview object.
lvma_How -- Please refer to the LVM_ADDENTRIES section for
more information on the ways you can add entries.
lvma_Flags -- Any of the following flags can be set here:
LVASF_MAKEVISIBLE -- This tell's the lisview object to
scroll the list to make the added entry
visible.
LVASF_SELECT -- This tell's the listview object to
make the added entry selected. This will also
automatically scroll the list to make the
added entry visible.
Returns TRUE uppon success, FALSE uppon failure.
LVM_CLEAR -- This method must be used to clear and delete all entries
present in the list. It uses the following custom message
structure:
struct lvmCommand {
ULONG MethodID; /* Several */
struct GadgetInfo *lvmc_GInfo; /* See note above. */
};
Return code is not defined.
LVM_FIRSTENTRY, LVM_LASTENTRY, LVM_NEXTENTRY, LVM_PREVENTRY -- These
methods must be used to itterate through all entries in the
listview. All these methods use the following message
structure:
struct lvmGetEntry {
ULONG MethodID; /* Any of the above. */
APTR lvmg_Previous;
ULONG lvmg_Flags;
};
lvmg_Previous -- For the LVM_FIRSTENTRY and LVM_LASTENTRY
methods this must be NULL. For the LVM_NEXTENTRY and
LVM_PREVENTRY this should point to the entry returned
by a previous call to any of these methods.
lvmg_Flags -- Any of the following flags may be set here:
LVGEF_SELECTED -- The methods will only scan for
selected entries when this bit is set. All
non-selected entries will simply be skipped.
Returns a pointer to the entry or NULL when no more entries
are available.
Example:
/*
** Scan through all entries in
** the listview gadget starting
** at the first one.
**/
Object *listview;
APTR entry;
/*
** Get first entry.
**/
if ( entry = (APTR)DoMethod(
listview, LVM_FIRSTENTRY, NULL, 0L )) {
/*
** Loop through the rest of the list.
**/
do {
/*
** Print the entry...
**/
printf( "Entry = %s\n", entry );
/*
** Next entry...
**/
entry = (APTR)DoMethod(
listview, LVM_NEXTENTRY, entry, 0L );
} while ( entry );
}
LVM_REMENTRY -- This method must be used to remove a single entry from
the listview object. It uses the following custom message
structure:
struct lvmRemEntry {
ULONG MethodID; /* LVM_REMENTRY */
struct GadgetInfo *lvmr_GInfo; /* See note above. */
APTR lvmr_Entry;
};
lvmr_Entry -- This must point to the entry you want to remove.
This usually is a pointer returned to you by either
the LVM_FIRSTENTRY, LVM_LASTENTRY, LVM_NEXTENTRY or
LVM_PREVENTRY method.
Return code is not defined.
LVM_REFRESH -- This method must be used to refresh the listview object
after some changes have been made which where not visible. In
some cases it might be usefull to add entries without passing
a GadgetInfo structure along with the adding methods. This
will speed up the adding and you can show the changes when you
are done by sending this method to the listview object.
This method uses the same custom message structure as defined
above at the LVM_CLEAR method.
Return code is not defined.
LVM_SORT -- Calling this method will force a complete re-sorting of
the entries in the list. This can be handy when your
comparisson hook (described in the Attributes section) can
handle different kinds of comparissons.
This method uses the same custom message structure as defined
above at the LVM_CLEAR method.
Return code is not defined.
LVM_LOCKLIST, LVM_UNLOCKLIST -- These methods must be used to lock
or unlock the list contents. When, for example, you must
change the text of a list entry you should lock it using the
LVM_LOCKLIST method and when you are done unlock it using the
LVM_UNLOCKLIST method. This locking is necessary while the
list may get referenced while you are doing your changes.
Both methods use the same custom message structure as defined
above at the LVM_CLEAR method.
LVM_MOVE ** V38 ** -- This method must be used to move entries in the
list. This method uses the following custom message structure:
struct lvmMove {
ULONG MethodID; /* LVM_MOVE */
struct GadgetInfo *lvmm_GInfo; /* GadgetInfo */
APTR lvmm_Entry;
ULONG lvmm_Direction;
};
lvmm_Entry -- This can point to the specific entry you want to
move. If you specify NULL here the selected entry is
moved.
lvmm_Direction -- Here you can specify the direction in which
the entry must be moved. The following directions are
possible:
LVMOVE_UP -- Move the entry one place up.
LVMOVE_DOWN -- Move the entry one place down.
LVMOVE_TOP -- Move the entry to the list-top.
LVMOVE_BOTTOM -- Move the entry to the list-bottom.
When the entry actually moved the class will send out a
notification message with the following attributes:
GA_ID -- The ID of the object.
LISTV_NewPosition -- The new numeric position of the
entry.
Returns TRUE when the entry moved and FALSE if not.
CHANGED METHODS
None.
listviewclass/Attributes listviewclass/Attributes
NAME
LISTV_ResourceHook -- ( struct Hook * )
FUNCTION
To add a hook routine that will build or delete a listview entry. The
hook routine will be called as follows:
rc = hookFunc( hook, object, message );
D0 A0 A2 A1
APTR rc;
struct Hook *hook;
Object *object;
struct lvRender *message;
The message arguments is a pointer to the following data structure:
struct lvResource {
UWORD lvr_Command;
APTR lvr_Entry;
};
lvr_Command -- This can be LVRC_MAKE which means that the hook should
create an entry or it can be LVRC_KILL which means that the
hook must dispose of a previously created entry.
lvr_Entry -- When this is a LVRC_MAKE command this contains the data
added to the listview by one of the adding methods or
attributes. When this is a LVRC_KILL command this points to
whatever LVRC_MAKE has created.
The default creating/deletion that is done by the listview expects the
entries to be simple string pointers. Internally these strings are
copied to an internal buffer when the entry is created. When the entry
is disposed of the string copy is simply de-allocated. If you add
entries to the listview which are not string pointers you must supply
your own resource handling using this attribute.
Example:
/*
** This example takes a PubScreenNode as input,
** copies the name and adds that to the listview.
** Uppon deletion it simply de-allocates the copy
** of the string.
**/
__saveds __asm APTR
hookFunc( register __a0 struct Hook *hook,
register __a2 Object *object,
register __a1 struct lvResource *lvr )
{
struct PubScreenNode *psn =
( struct PubScreenNode * )lvr->lvr_Entry;
UWORD len;
APTR rc = NULL;
/*
** Built or dispose?
**/
switch ( lvr->lvr_Command ) {
case LVRC_MAKE:
/*
** Determine string size.
**/
len = strlen( psn->psn_Node.ln_name ) + 1;
/*
** Allocate and copy the string.
**/
if ( rc = ( APTR )AllocVec( len, MEMF_ANY ))
strcpy(( UBYTE * )rc, psn->psn_Node.ln_Name );
break;
case LVRC_KILL:
/*
** Simply de-allocate whats created above.
**/
FreeVec( lvr->lvr_Entry );
break;
}
/*
** 'rc' will be a pointer to the created
** string copy or NULL which indicates a
** memory error with LVRC_MAKE. If rc is non-NULL
** the string is added to the list of entries.
**/
return( rc );
}
The hook must return a pointer to the data created when the command is
LVRC_MAKE. When the command is LVRC_MAKE and NULL is returned the
entry will not be added to the list.
LVRC_KILL commands do not have a return code defined.
Default is NULL (internal memory handling). Applicability is (I).
SEE ALSO
LISTV_DisplayHook, LISTV_CompareHook
NAME
LISTV_DisplayHook -- ( struct Hook * )
FUNCTION
To add a hook routine that will take care of rendering the entries. In
some cases it is necessary to do your own rendering. This hook is
called for each entry that needs to be rendered. The hook routine will
be called as follows:
rc = hookFunc( hook, object, message );
D0 A0 A2 A1
VOID rc; /* No return code defined. */
struct Hook *hook;
Object *object;
struct lvRender *message;
The message argument is a pointer to the following data structure:
struct lvRender {
struct RastPort *lvr_RPort;
struct DrawInfo *lvr_DrawInfo;
struct Rectangle *lvr_Bounds;
APTR lvr_Entry;
UWORD lvr_State;
UWORD lvr_Flags;
};
lvr_RPort -- This is a pointer to the RastPort in which the rendering
must be done. Please note that the font you must use to render
text is already set up for you. It is not recommendable to
use another font than the one set in this RastPort because the
height of the area you may render in is setup accoording to
this font.
lvr_DrawInfo -- This can point to a DrawInfo structure as defined in
<intuition/screens.h> in which the necessay information about
the display environment is stored. Note that it is possible
that this is NULL. It is not very likely but it is possible.
lvr_Bounds -- This is a struct Rectangle in which the area you should
render in is defined. Do _not_ render outside the given bounds
or you will seriously screw up the display! Also keep in mind
that the area you are rendering into is not always cleared. In
other words, the area may still show data from another entry.
You must make sure you completely re-render the given bounds.
lvr_Entry -- This points to the entry data as setup by the entry
creation hook or the built-in entry creation.
lvr_State -- This describes the state in which to render the entry.
The state is one of the following possibilities:
LVRS_NORMAL -- Normal rendering. Render the entry in a normal,
un-selected way.
LVRS_SELECTED -- Selected rendering. Render the entry in a
selected way.
LVRS_NORMAL_DISABLED -- Normal, disabled rendering. Render the
entry in a normal way but make it disabled. This is
normally done by ghosting it with a pattern (see
below).
LVRS_SELECTED_DISABLED -- Selected, disabled rendering. Render
the entry is a selected way but make it disabled. This
is normally done by ghosting it with a pattern (see
below).
Ghosting the entry is usually done like this:
struct lvRender *lvr;
UWORD *pens = lvr->lvr_DrawInfo->dri_Pens;
UWORD patt = { 0x2222, 0x8888 };
SetAPen( lvr->lvr_RPort, pens[ SHADOWPEN ] );
SetDrMd( lvr->lvr_RPort, JAM1 );
SetAfPt( lvr->lvr_RPort, patt, 1 );
RectFill( lvr->lvr_RPort, lvr->lvr_Bounds.MinX,
lvr->lvr_Bounds.MinY,
lvr->lvr_Bounds.MaxX,
lvr->lvr_Bounds.MaxY );
Please keep in mind that, although the above code doesn't show
it, the lvr_DrawInfo field can be NULL.
lvr_Flags -- No flags are defined yet.
When this hook is not set the internal rendering routine will simply
render a string which is created in the LIST_ResourceHook. When the
LISTV_RenderHook routine creates something other than a simple string
pointer you must provide a display hook to render the entries.
Most of the time when you add more than a simple string to the
listview object the data you add is a structure which contains the
string and some extra data. To prevent you from having to write a
display-hook to render the string your hook can also simply return a
pointer to the string and the listviewclass will render it for you.
I.E.:
struct myStruct {
UBYTE *string;
UWORD some_more_data;
};
__saveds __asm hookFunc( register __a0 struct Hook *hook,
register __a2 Object *lv_obj,
register __a1 struct lvRender *lvr )
{
return((( struct myNode * )lvr->lvr_Entry )->string );
}
This hook will let the listviewclass dispatcher render the returned
string for you while keeping the extended data available for you. If
your hook returns NULL the listviewclass assumes you have done all
rendering required.
Default is NULL (internal entry rendering). Applicability is (I).
SEE ALSO
LISTV_ResourceHook, LISTV_CompareHook, LISTV_TitleHook
NAME
LISTV_CompareHook -- ( struct Hook * )
FUNCTION
To add a hook routine that will compare two entries with eachother.
As it is possible to have entries which are different from simple
strings you can perform your own comparison here. The comparison hook
is called each time an entry is added sorted or when the list is re-
sorted. The hook routine will be called as follows:
rc = hookFunc( hook, object, message );
D0 A0 A2 A1
LONG rc;
struct Hook *hook;
Object *object;
struct lvCompare *message;
The message argument is a pointer to the following data structure:
struct lvCompare {
APTR lvc_EntryA;
APTR lvc_EntryB;
};
lvc_EntryA, lvc_EntryB -- These are the entries that must be compared
to eachother.
The internal comparison routine simple does a stricmp() on the two
entry strings.
This hook must return -1 when entry a is smaller than entry b, 0 when
entry a is equal to entry b and 1 when entry a is bigger than entry b.
Default is NULL (internal comparison routine). Applicability is (I).
SEE ALSO
LISTV_ResourceHook, LISTV_DisplayHook
NAME
LISTV_Top -- ( ULONG )
FUNCTION
Set the top-entry of the visible part of the list. This tag is mostly
used by the prop object that is connected to the listview but it can
also be controlled by your program. The data of this tag must be the
number of the node to set at the top of the visible area.
Default is 0. Applicability is (ISGU).
NAME
LISTV_ListFont -- ( struct TextAttr )
FUNCTION
To set the font which is used to render the entries. By default the
font used to render the entries is the same font which is used to
render the object it's label. This font might be proportional. In some
cases it might be useful to have a mono-space font for the entries or
even another proportional font.
Default is NULL. Applicability is (IG)
NAME
LISTV_ReadOnly -- ( BOOL )
FUNCTION
To make the listview a read-only object. Read only objects have full
functionality except for the entries which cannot be selected.
Default is FALSE. Applicability is (I).
NAME
LISTV_MultiSelect -- ( BOOL )
FUNCTION
To make the listview a multi-selection object. Multi-selection objects
allow the user to select more than one entry from the list.
Default is FALSE. Applicability is (I).
NAME
LISTV_EntryArray -- ( APTR * )
FUNCTION
To add a set of entries at initialization time. The data is a pointer
to a NULL-terminated array of entries which need to be added to the
listview object.
Default is NULL. Applicability is (I).
SEE ALSO
LISTV_SortEntryArray
NAME
LISTV_SortEntryArray -- ( BOOL )
FUNCTION
To sort the entries added at object create time. By default the
entries added with the LISTV_EntryArray attribute will ocure in the
list in the same order as they ocure in the array. When this attribute
is set to TRUE these entries will be sorted.
Default is FALSE. Applicability is (I).
SEE ALSO
LISTV_EntryArray
NAME
LISTV_Select -- ( ULONG )
FUNCTION
To select an entry in the list. The entry you select will also be made
visible in the display area. The data required is the logical
number of the entry in the list starting with 0 as the first entry.
The following magic numbers are allowed in the tag it's data field:
LISTV_Select_First -- Select the first entry. ** V38 **
LISTV_Select_Last -- Select the last entry. ** V38 **
LISTV_Select_Next -- Select the next entry. If there is no entry
selected yet the first visible entry is selected. ** V38 **
LISTV_Select_Previous -- Select the previous entry. If there is no
selected entry yet the first visible entry is selected.
** V38 **
LISTV_Select_Top -- Select the first visible entry. ** V38 **
LISTV_Select_Page_Up -- Select the entry one page above the current.
If the currently selected entry is not the top-entry the top
entry will be selected. Otherwise the entry one-page up minus
one is selected. When no entry is selected the first visible
entry is selected. ** V38 **
LISTV_Select_Page_Down -- Select the entry one page below the current.
If the currently selected entry is not the bottom-entry the
bottom entry will be selected. Otherwise the entry one-page
down minus one is selected. When no entry is selected the
first visible entry is selected. ** V38 **
Applicability is (SU).
NAME
LISTV_MakeVisible -- ( ULONG )
FUNCTION
To scroll the list to make the entry appear in the display area of the
listview object. The data required is the logical number of the entry
in the list starting with 0 as the first entry.
Applicability is (SU).
NAME
LISTV_Entry -- ( APTR )
FUNCTION
This tag is sent during notification. The data field is a pointer to
the entry which triggered the notification.
Applicability is (N).
SEE ALSO
LISTV_EntryNumber
NAME
LISTV_EntryNumber -- ( ULONG )
FUNCTION
This tag is sent during notification. The data field is the logical
number of the entry which triggered the notification.
Applicability is (N).
SEE ALSO
LISTV_Entry
NAME
LISTV_LastClicked -- ( APTR )
FUNCTION
To get a pointer to the last selected entry. This data can be used to
detect double-clicking and entry.
Example:
Object *listview;
ULONG ds[2], dm[2], last = 0, clicked;
GetAttr( LISTV_LastClicked, listview, &clicked );
if ( clicked == last ) {
CurrentTime( &ds[ 1 ], &dm[ 1 ] );
if ( DoubleClick( ds[ 0 ], dm[ 0 ], ds[ 1 ], dm [ 1 ] )) {
/* Double clicked */
...
}
}
CurrentTime( &ds[ 0 ], &dm[ 0 ] );
last = clicked;
Applicability is (G).
SEE ALSO
LISTV_LastClickedNum
NAME
LISTV_TitleHook -- ( struct Hook * )
FUNCTION
To add a hook to render a title for the list. Multi-column listviews
normally have a title entry which is rendered in the list area but
does not scroll with the list. To support multi-column listviews this
hook can be defined which will keep room for a single entry at the top
of the list area which is reserved for this purpose. The hook routine
is called exactly the same as the LISTV_DisplayHook routine with the
exception that the lvr_Entry field of the lvRender structure will
contain a NULL pointer.
Default is NULL (no title). Applicability is (I).
NAME
LISTV_ThinFrames -- ( BOOL )
FUNCTION
To make all listview object framing appear as thin frames. This will
help you to make an aspect-ratio dependant GUI.
Default is FALSE. Applicability is (I).
NAME
PGA_NewLook -- ( BOOL )
FUNCTION
To make the scroller of the listview gadget appear in the new look.
Default is FALSE. Applicability is (I).
NAME
LISTV_LastClickedNum -- ( ULONG ) ** V38 **
FUNCTION
To return the number of the last selected entry.
Applicability is (G).
SEE ALSO
LISTV_LastClicked
NAME
LISTV_NumEntries ( ULONG ) ** V38 **
FUNCTION
To return the number of entries in the list.
Applicability is (G).
NAME
LISTV_NewPosition -- ( ULONG ) ** V38 **
FUNCTION
To notify the object it's targets of the entry it's new position
number. When you move an entry with the LVM_MOVE method the object
will send out a notification message with this attribute.
Applicability is (N).
SEE ALSO
LVM_MOVE
NAME
LISTV_MinEntriesShown -- ( UWORD )
FUNCTION
To specify how many entries should be visible at all times. Note: The
larger this value the bigger the object it's minimum size.
Default is 3. Applicability is (I).
